package net.strglr.blu.example.sldoc;

// Note that the SLDoc tags have long namespaces, but that can be changed in the taglet module

/**
 * Demonstration class.
 * <br/> Please read the source code of this class for a better understanding.
 * <br/> Some browsers might not display the SVG images below (e.g. Firefox 3)
 * <br/> The methods in this class are irrelevant.
 * @author stellabs
 * @version 0.1
 */
abstract public class Example1 {
  /**
   * This illustrates some of the usages of the SlDoc taglet.
   * 

   * <br/> Resources can be located in this package transposed doc
   * dir:
   * <br>{@sldoc.refer.image targettype="png" "Example1_0.gv"}
   * <br>{@sldoc.refer.image targettype="png" "../Example1_0.gv"}
   * <br>{@sldoc.refer.image targettype="png" usedocroot="true" "/net/strglr/blu/Example1_0.gv"}
   * <br>(images rendered as PNG)
   * 
   * <br> Or in the file system if the resource path is absolute and 'usedocroot'
   * isn't specified or is set to "false". (can't be shown here) <br> 
   * <br/> If a processing error occurs, it's shown in the API doc, so that it can
   * be detected by the proofreader:
   * {@sldoc.refer.image alt="[error example]" "Example1.img"}
   */
  public static void main(String[] args) {
    System.out.println("-----------------------------------------------");
    System.out.println("| Dummy class for BlueStraggler/SlDoc demo    |");
    System.out.println("-----------------------------------------------");
  }
  
  /**
   * Insert a reference to an image after converting it.
   * Images can be displayed with the {@code {@sldoc.refer.image ...} } tag.<br/><br/>
   * Here a GML graph "Example1_1.gml" is converted into an
   * image and displayed below with a height of 100:<br/>
   * {@sldoc.refer.image alt="[svg rendering]" height="100" "Example1_1.gml"}
   * <br/>Actually, most of the HTML IMG tag attributes can be used:
   * {@sldoc.refer.image height="120" width="120" align="middle" alt="[svg rendering]" "Example1_1.gml"}
   * 
   * <br/> Currently, Graphviz (.gv: DOT language):{@sldoc.refer.image alt="[svg rendering]" height="150" align="middle" "Example1_2.gv"}
   * and GXL:{@sldoc.refer.image alt="[svg rendering]" height="150" align="middle" "Example1_3.gxl"}
   * formats are also supported.<br/>
   * Other image formats <b>can easily be handled</b>, for instance by adding shell commands that invoke
   * converters.<br/>
   * 
   */
  abstract void displayImage();
  
  /**
   * Insert a text file contents.
   * Text can be displayed with the {@code {@sldoc.include.text ...} } tag.<br/><br/>
   * 
   * Plain text can be inserted -> {@sldoc.include.text "Example1_4.txt"}<br>
   * Plain HTML can be inserted too -> {@sldoc.include.text origintype="plainhtml" "Example1_5.html"}<br>   
   * <br>More interesting is the recursive ability to include HTML files that contain taglets themselves!<br>
   * {@sldoc.include.text origintype="html" "Example1_6.html"}
   */
  abstract void displayText();
  
  /**
   * A minor feature to display an update date.
   * It can be displayed with the {@code  @sldoc.update ... } tag.
   * @sldoc.update 25/Nov/2011
   */
  abstract void displayUpdate();
  
  /**
   * This file contents.
   * <table border="1">
   * <tr>
   * <td>{@sldoc.include.text usedocroot="true" "/../src/net/strglr/blu/example/sldoc/Example1.java"}</td>
   * </tr>
   * </table>  
   */
  abstract void showSource();
}
